Expand description
Kube is an umbrella-crate for interacting with Kubernetes in Rust.
§Overview
Kube contains a Kubernetes client, a controller runtime, a custom resource derive, and various tooling required for building applications or controllers that interact with Kubernetes.
The main modules are:
client
with the KubernetesClient
and its layersconfig
for clusterConfig
api
with the generic KubernetesApi
derive
with theCustomResource
derive for building controllers typesruntime
with aController
/watcher
/reflector
/Store
core
with generics fromapimachinery
You can use each of these as you need with the help of the exported features.
§Using the Client
use futures::{StreamExt, TryStreamExt};
use kube::{Client, api::{Api, ResourceExt, ListParams, PostParams}};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Infer the runtime environment and try to create a Kubernetes Client
let client = Client::try_default().await?;
// Read pods in the configured namespace into the typed interface from k8s-openapi
let pods: Api<Pod> = Api::default_namespaced(client);
for p in pods.list(&ListParams::default()).await? {
println!("found pod {}", p.name_any());
}
Ok(())
}
For details, see:
Client
for the extensible Kubernetes clientApi
for the generic api methods available on Kubernetes resources- k8s-openapi for documentation about the generated Kubernetes types
§Using the Runtime with the Derive macro
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::json;
use futures::{StreamExt, TryStreamExt};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
use kube::{
api::{Api, DeleteParams, PatchParams, Patch, ResourceExt},
core::CustomResourceExt,
Client, CustomResource,
runtime::{watcher, WatchStreamExt, wait::{conditions, await_condition}},
};
// Our custom resource
#[derive(CustomResource, Deserialize, Serialize, Clone, Debug, JsonSchema)]
#[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
pub struct FooSpec {
info: String,
#[schemars(length(min = 3))]
name: String,
replicas: i32,
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::try_default().await?;
let crds: Api<CustomResourceDefinition> = Api::all(client.clone());
// Apply the CRD so users can create Foo instances in Kubernetes
crds.patch("foos.clux.dev",
&PatchParams::apply("my_manager"),
&Patch::Apply(Foo::crd())
).await?;
// Wait for the CRD to be ready
tokio::time::timeout(
std::time::Duration::from_secs(10),
await_condition(crds, "foos.clux.dev", conditions::is_crd_established())
).await?;
// Watch for changes to foos in the configured namespace
let foos: Api<Foo> = Api::default_namespaced(client.clone());
let wc = watcher::Config::default();
let mut apply_stream = watcher(foos, wc).applied_objects().boxed();
while let Some(f) = apply_stream.try_next().await? {
println!("saw apply to {}", f.name_any());
}
Ok(())
}
For details, see:
CustomResource
for documentation how to configure custom resourcesruntime::watcher
for how to long-running watches work and why you want to use this overApi::watch
runtime
for abstractions that help with more complicated Kubernetes application
§Examples
A large list of complete, runnable examples with explainations are available in the examples folder.
Modules§
- api
client
API helpers for structured interaction with the Kubernetes API - client
client
A basic API client for interacting with the Kubernetes API - config
config
- Re-exports from
kube_core
Crate with types and traits necessary for interacting with the Kubernetes API - discovery
client
High-level utilities for runtime API discovery. - error
config
orclient
Error handling and error types - runtime
runtime
Re-exports fromkube-runtime
Common components for building Kubernetes operators
Structs§
- Api
client
The generic Api abstraction - Client
client
Client for connecting with a Kubernetes cluster. - Config
config
Configuration object detailing things like cluster URL, default namespace, root certificates, and timeouts. - Discovery
client
A caching client for running API discovery against the Kubernetes API.
Enums§
Traits§
- Extension trait that is implemented by kube-derive
- An accessor trait for a kubernetes Resource.
- Helper methods for resources.
Type Aliases§
- Result
config
orclient
Convient alias forResult<T, Error>
Derive Macros§
- CustomResource
derive
Re-exports fromkube-derive
A custom derive for kubernetes custom resource definitions.